<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>
<head>

  <meta http-equiv="Content-Language" content="en-us">


  <title>IupButton</title>
  <link rel="stylesheet" type="text/css" href="../../style.css">

  <style type="text/css">
.style1 {
	margin-left: 40px;
}
  </style>
</head>


<body>

<div id="navigation">
  
<ul>

    <li><a href="#Creation">Creation</a></li>

    <li><a href="#Attributes">Attributes</a></li>

    <li><a href="#Callbacks">Callbacks</a></li>

    <li><a href="#Notes">Notes</a></li>

    <li><a href="#Examples">Examples</a></li>

    <li><a href="#SeeAlso">See Also</a></li>

  
</ul>

</div>


<h2>IupButton</h2>


  
<p>
  Creates an interface element that is a 
  button. When selected, this element activates a function in the application. Its visual presentation can contain a 
  text and/or an image.</p>


<h3><a name="Creation">Creation</a></h3>


<pre>Ihandle* IupButton(const char *<strong>title</strong>, const char *<strong>action</strong>); [in C]<br>iup.button{[title = <strong>title</strong>: string]} -&gt; <strong>elem</strong>: ihandle [in Lua]<br>button(<strong>title</strong>, <strong>action</strong>) [in LED]</pre>

  
<p><b>
  title</b>: Text to be shown to the user. It can be NULL. It will set the TITLE 
  attribute.<br>

  <b>
  action</b>: Name of the action generated when the button is selected. It can be NULL.</p>

  
<p>
  <u>Returns:</u> the identifier of the 
  created element, or NULL if an error occurs.</p>


<h3><a name="Attributes">Attributes</a></h3>



<p><b>ALIGNMENT</b> (<font size="3">non inheritable</font>):
  horizontal and vertical alignment. Possible values:
  "ALEFT", "ACENTER" and "ARIGHT",&nbsp; combined to "ATOP", "ACENTER" 
  and "ABOTTOM". 
  Default:
  "ACENTER:ACENTER". Partial values are also accepted, like "ARIGHT" or 
  ":ATOP", the other value will be used from the current alignment. In Motif, 
  vertical alignment is restricted to "ACENTER". In GTK, horizontal alignment 
for multiple lines will align only the text block. (since 3.0)</p>

<p><a href="../attrib/iup_bgcolor.html">BGCOLOR</a>:
  Background color. BGCOLOR is ignored always when FLAT=YES because it will 
inherit from the native parent. If text and image are not defined, the BGCOLOR 
is used to show a color not necessary as a background color of the button, in 
this case set the button size because the natural size will be very small. In Windows, when using the Windows driver or the GTK 
driver, the 
BGCOLOR attribute is ignored if text or image is defined. Default: the global 
attribute DLGBGCOLOR.</p>

<p><strong>CANFOCUS</strong> (creation only)<strong> </strong>(<font size="3">non inheritable</font>): enables the focus traversal of the control. In Windows the button will respect CANFOCUS in 
opposite to the other controls. Default: YES. (since 3.0)</p>

  
<p><b>FLAT</b> (creation only): Hides the button borders until the mouse enter the 
  button area. Can be YES or NO.</p>

<p><a href="../attrib/iup_fgcolor.html">FGCOLOR</a>: Text color. Default: the 
global attribute DLGFGCOLOR.</p>



  
<p><strong>IMAGE</strong> (<font size="3">non inheritable</font>):
  Image name. If set before map defines the behavior of the button to contain an 
  image. The natural size will be size of the image in pixels, plus the button 
	borders. Use <a href="../func/iupsethandle.html">IupSetHandle</a> or
	<a href="../func/iupsetattributehandle.html">IupSetAttributeHandle</a> to 
	associate an image to a name. See also <a href="iupimage.html">IupImage</a>. If TITLE is also defined 
	and not empty both will be shown (except in Motif). (GTK 2.6)</p>

  
<p><strong>IMINACTIVE</strong> (<font size="3">non inheritable</font>):
  Image 
  name of the element when inactive. If it is not defined  then the IMAGE is 
  used and the colors will be replaced by a modified version of the background color creating the disabled effect. 
	GTK will also change the inactive image to look like other inactive objects. 
(GTK 2.6)</p>

  
<p><strong>IMPRESS </strong>(<font size="3">non inheritable</font>): Image 
	name of the pressed button. If IMPRESS and IMAGE are defined, the button 
	borders are not shown and not computed in size 
	computation. When the button is clicked the pressed image does not offset. 
In Motif the button will lose its focus feedback also. (GTK 2.6)</p>

<p><strong>IMPRESSBORDER </strong>(<font size="3">non inheritable</font>): if 
enabled the button borders will be shown and computed even if IMPRESS is defined. Can be 
&quot;YES&quot; or &quot;NO&quot;. Default: &quot;NO&quot;. </p>

<p><strong>IMAGEPOSITION </strong>(<font size="3">non inheritable</font>): 
Position of the image relative to the text when both are displayed. Can be: 
LEFT, RIGHT, TOP, BOTTOM. Default: LEFT. (since 3.0) (GTK 2.10)</p>

  
<p><b>MARKUP</b> [GTK only]: allows the title string to contains pango markup 
  commands. Works only if a mnemonic is NOT defined in the title. Can be "YES" or "NO". Default: "NO". </p>

  
<p><b>PADDING</b>: internal margin. Works just like the MARGIN attribute of 
  the <strong>IupHbox</strong> and <strong>IupVbox</strong> containers, but uses a different name to avoid 
  inheritance problems. Default value: "0x0". 
	(since 3.0)</p>


<p><strong>SPACING </strong>(creation only): defines the spacing between the 
image associated and the button's text. Default: &quot;2&quot;.</p>

  
<p><a href="../attrib/iup_title.html">TITLE</a> (<font size="3">non inheritable</font>):
Button's text. If IMAGE is not defined before map, then the default
behavior is to contain only a text. The button behavior can not be changed
after map. The natural size will be larger enough to include all the
text in the selected font, even using multiple lines, plus the button
borders. The '\n' character is accepted for line change. The "&amp;"
character can be used to define a mnemonic, the next character will be
used as key. Use "&amp;&amp;" to show the "&amp;" character instead on
defining a mnemonic. The button can be activated from any control in
the dialog using the "Alt+key" combination. In old Motif versions (2.1) using a 
'\n' causes an invalid memory access inside Motif. (mnemonic support since 3.0)</p>



  
<blockquote>
    
  <hr>
</blockquote>

<p>
<a href="../attrib/iup_active.html">ACTIVE</a>,
<a href="../attrib/iup_font.html">FONT</a>, 
    <a href="../attrib/iup_expand.html">EXPAND</a>, <a href="../attrib/iup_screenposition.html">SCREENPOSITION</a>, 
<a href="../attrib/iup_position.html">
POSITION</a>, <a href="../attrib/iup_minsize.html">
MINSIZE</a>, <a href="../attrib/iup_maxsize.html">
MAXSIZE</a>,
    <a href="../attrib/iup_wid.html">WID</a>, <a href="../attrib/iup_tip.html">TIP</a>, <a href="../attrib/iup_size.html">SIZE</a>, 
<a href="../attrib/iup_rastersize.html">RASTERSIZE</a>,
    <a href="../attrib/iup_zorder.html">ZORDER</a>, <a href="../attrib/iup_visible.html">VISIBLE</a>: 
also accepted.</p>


<h3><a name="Callbacks">Callbacks</a></h3>


<p><a href="../call/iup_action.html">ACTION</a>:
  Action generated when the button 1 (usually 
  left) is selected. This callback is called only after the mouse is released and when it is released inside the 
  button area.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>); [in C]<br><strong>elem</strong>:action() -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.</p>

<p class="info"><u>Returns</u>: IUP_CLOSE will be processed.</p>

  
<p><a href="../call/iup_button_cb.html">BUTTON_CB</a>:
  Action generated when any mouse button is 
  pressed and released.</p>

    
<hr class="style1">

<p> 
<a href="../call/iup_map_cb.html">MAP_CB</a>, 
<a href="../call/iup_unmap_cb.html">UNMAP_CB</a>, <a href="../call/iup_getfocus_cb.html">GETFOCUS_CB</a>,
  <a href="../call/iup_killfocus_cb.html">KILLFOCUS_CB</a>, 
<a href="../call/iup_enterwindow_cb.html">ENTERWINDOW_CB</a>,
  <a href="../call/iup_leavewindow_cb.html">LEAVEWINDOW_CB</a>, 
<a href="../call/iup_k_any.html">K_ANY</a>,
  <a href="../call/iup_help_cb.html">HELP_CB</a>: All common callbacks are 
supported.</p>


<h3><a name="Notes">Notes</a></h3>


<p>Buttons with images and/or texts can not change its behavior after mapped. This is a creation 
dependency. But after 
  creation the image can be changed for another image, and the text for another text.</p>

  
<p>Buttons are activated using Enter or Space keys.</p>


<h3><a name="Examples">Examples</a></h3>

<p><a href="../../examples/">Browse for Example Files</a></p>

<p>The buttons with image and text simultaneous have PADDING=5x5, the other 
buttons have no padding. The buttons with no text and BGCOLOR defined have their 
RASTERSIZE set.</p>

<table align="center">

	<tbody>
    <tr>

		<th>Motif</th>

		<th>Windows <br>

		Classic</th>

		<th>Windows <br>

		w/ Styles</th>

		<th>GTK</th>

	</tr>

	<tr>

		<td class="bg_mot"><img src="images/iupbutton_mot_imagetext.png"></td>

		<td class="bg_win2k"><img src="images/iupbutton_win2k_imagetext.png"></td>

		<td class="bg_winxp"><img src="images/iupbutton_winxp_imagetext.png"></td>

		<td class="bg_gtk"><img src="images/iupbutton_gtk_imagetext.png"></td>

	</tr>

	<tr>

		<td class="bg_mot"><img src="images/iupbutton_mot_text.png"></td>

		<td class="bg_win2k"><img src="images/iupbutton_win2k_text.png"></td>

		<td class="bg_winxp"><img src="images/iupbutton_winxp_text.png"></td>

		<td class="bg_gtk"><img src="images/iupbutton_gtk_text.png"></td>

	</tr>

	<tr>

		<td class="bg_mot"><img src="images/iupbutton_mot_image.png"></td>

		<td class="bg_win2k"><img src="images/iupbutton_win2k_image.png"></td>

		<td class="bg_winxp"><img src="images/iupbutton_winxp_image.png"></td>

		<td class="bg_gtk"><img src="images/iupbutton_gtk_image.png"></td>

	</tr>
	
	<tr>

		<td class="bg_mot"><img src="images/iupbutton_mot_bgcolor.png"></td>

		<td class="bg_win2k"><img src="images/iupbutton_win2k_bgcolor.png"></td>

		<td class="bg_winxp"><img src="images/iupbutton_winxp_bgcolor.png"></td>

		<td class="bg_gtk"><img src="images/iupbutton_gtk_bgcolor.png"></td>

	</tr>

  </tbody>
</table>


<h3><a name="SeeAlso">See Also</a></h3>


<p><a href="iupimage.html">IupImage</a>, <a href="iuptoggle.html">IupToggle</a>,
<a href="iuplabel.html">IupButton</a></p>



</body>
</html>
